[% setvar title The Predefined POD Streams are C<perl>, C<data>, and C<doc> %]
<div id="archive-notice">
    <h3>This file is part of the Perl 6 Archive</h3>
    <p>To see what is currently happening visit <a href="http://www.perl6.org/">http://www.perl6.org/</a></p>
</div>
<div class='pod'>
<a name='TITLE'></a><h1>TITLE</h1>
<p>The Predefined POD Streams are <code>perl</code>, <code>data</code>, and <code>doc</code></p>
<a name='VERSION'></a><h1>VERSION</h1>
<pre>  Maintainer: John Porter &lt;<a href='mailto:jdporter@min.net'>jdporter@min.net</a>&gt;
  Date: 9 Aug 2000
  Last Modified: 7 Sep 2000
  Mailing List: <a href='mailto:perl6-language@perl.org'>perl6-language@perl.org</a>
  Number: 79
  Version: 3
  Status: Developing</pre>
<a name='ABSTRACT'></a><h1>ABSTRACT</h1>
<p>Source files are pre-processed through a filter which breaks the text
into multiple &quot;streams&quot; of paragraphs, using POD directives.
Perl code, documentation (&quot;POD&quot;), and data are three pre-defined
such streams, introduced by <code>=perl</code>, <code>=doc</code>, and <code>=data</code>
directives, respectively.  A special (global?) hash of filehandles
is created, keyed as appropriate, enabling user code to read the
streams of perl code, documentation, and data.</p>
<p>This unifies perl5's <code>__DATA__</code> with POD, and allows any text to
be both code and documentation.</p>
<a name='CHANGES'></a><h1>CHANGES</h1>
<p>Version 2 of this RFC was entitled &quot;Perl Compiler is Just Another Pod Processor&quot;.</p>
<p>Versions 1 and 2 failed to distinguish between the input streams, and the
special pod formatter diversions.  This version makes the distinction clear,
and furthermore asserts the use of <code>=begin</code>/<code>=end</code> for the former only.</p>
<p>Version 1 of this RFC was entitled &quot;Code which is both executable and POD&quot;.</p>
<p>Version 1 of this RFC proposed a special &quot;perl&quot; POD processor type.
Version 2 made the &quot;perl&quot; type non-special.  This version calls &quot;perl&quot;,
&quot;doc&quot;, and &quot;data&quot; streams, as distinct from POD processor types.</p>
<p>Version 1 proposed a simple implementation which could theoretically work
with the perl5 front end.  Later versions presume that the perl6 front end
is game for any implementation details necessary to support the proposal.</p>
<a name='DESCRIPTION'></a><h1>DESCRIPTION</h1>
<p>Each file is treated as a set of (possibly entertwined) text streams, of
which three are predefined: perl code, data, and documentation.  Which
stream a given paragraph belongs to is controlled by POD-style directives,
<code>=begin</code> and <code>=end</code>, each of which take one or more optional arguments
naming the affected stream.  Multiple directives can be combined on a
single line, separated by commas.
A special alias, <code>all</code>, refers to all known streams.</p>
<pre>	=end all, begin doc

	This here is documentation, and nothin' else.

	=end</pre>
<p>Note that an <code>=end</code> directive with no arguments causes the effects of
the most recent <code>=begin</code> to be reversed -- in this example, the <code>doc</code>
stream is ended and the previous streams resumed.</p>
<p>As a convenience, some shorthand directives are defined:</p>
<pre>	=perl
	=data
	=doc</pre>
<p>which are equivalent, respectively, to:</p>
<pre>	=end all, begin perl
	=end all, begin data
	=end all, begin doc</pre>
<p>So the above example may be written as:</p>
<pre>	=doc

	This here is documentation, and nothin' else.

	=end</pre>
<p>Note that the <code>code</code> stream is always implicitly in effect at the
beginning of each file/module.</p>
<a name='How the Streams are Used'></a><h2>How the Streams are Used</h2>
<p>The user code in the current module may read any of the streams.</p>
<a name='DATA Section'></a><h3>DATA Section</h3>
<p>To read the data section, user code can do something like this:</p>
<pre>	while ( $pod{'data'}-&gt;readline ) { ...</pre>
<p>which will be the direct replacement for older perls'</p>
<pre>	while ( &lt;DATA&gt; ) { ...</pre>
<a name='POD Processors'></a><h3>POD Processors</h3>
<p>When a POD processor goes to scan a file for documentation, it
need only request that the POD streams be initialized (by whatever
mechanism is created to do this -- see <i><a href='#IMPLEMENTATION'>&quot;IMPLEMENTATION&quot;</a></i>),
and then it uses the <code>$pod{'doc'}</code> filehandle, or something like it.</p>
<a name='Perl Source Code Stream'></a><h3>Perl Source Code Stream</h3>
<p>The perl compiler sees only the stream of text from the <code>perl</code> stream,
which is also available to the user code via a special filehandle,
something like <code>$pod{'perl'}</code>.</p>
<a name='Affect on Special POD Formatters'></a><h2>Affect on Special POD Formatters</h2>
<p>This RFC usurps the <code>=begin</code> and <code>=end</code> directives, which are used in
previous versions of Perl to designate sections for special POD formatters.
Some replacement for these should be devised.</p>
<p>It does not affect the existing semantics of <code>=for</code>.</p>
<a name='Combining Code and Documentation'></a><h2>Combining Code and Documentation</h2>
<p>One of the motivations for this RFC was to allow arbitrary text to be
treated as both executable perl code and as documentation, thus allowing
actual perl code to appear in POD-generated documentation.  Example:</p>
<pre>	=begin code doc

	sub foo($$$$) {
		my( $marg, $bar, $sheitane, $bozorg ) = @_;

	=end

		# non-doc code here...
	}</pre>
<p>This shows the declaration of a subroutine being both actual perl code
and appearing in the doc stream.</p>
<a name='IMPLEMENTATION'></a><h1>IMPLEMENTATION</h1>
<p>The POD specification is modified from its perl5 form, to allow
&quot;streams&quot; of input paragraphs not only of <code>pod</code>, but also <code>data</code>,
and, for uniformity, <code>perl</code>.  All of them are readable via special
filehandles, localized in a special (global?) hash of filehandles.
<code>=pod</code>, etc., are implemented as shorthands for directives built
on <code>=begin</code>.  Furthermore, a special pseudo-stream name, <code>all</code>,
is an alias for all known stream names, i.e. <code>perl</code>, <code>data</code>, and <code>doc</code>.</p>
<p>The perl compiler reads input from the <code>perl</code> stream.</p>
<p>The <code>=cut</code> POD directive is disused.</p>
<p>The mechanism which parses the file, looking for <code>=begin</code>/<code>=end</code>
directives must be called implicitly whenever perl loads a source
file, and set up a hash to contain the special filehandles by which
the various pod streams can be read.  Probably the best way to do
this is to reserve a global hash variable to hold them, and localize
the values of it for the scope of the file.</p>
<p>In addition, the above-mentioned parsing mechanism should be callable
explicitly from user code; it would take a hash (by reference), and
a file name.  This feature will be needed by POD processing systems.
For example, a POD processor would do something like this:</p>
<pre>	my $file_having_doco = shift;
	my %pod_streams;
	parse_pod_streams( %pod_streams, $file_having_doco );
	local $/ = &quot;&quot;;
	while ( $pod_streams{'doc'}-&gt;readline ) {
		# process a paragraph.
	}</pre>
<p>The parsing mechanism will need to maintain a stack of &quot;currently
open streams&quot;, since a bare <code>=end</code> reverts to the set of streams in effect
before the nearest preceding <code>=begin</code>.</p>
<a name='REFERENCES'></a><h1>REFERENCES</h1>
<p>&quot;access to pod/doc text by code&quot;, mail thread rooted at
<a href='http://www.mail-archive.com/perl6-language@perl.org/msg01471.html' target='_blank'>www.mail-archive.com</a></p>
<p>RFC  5: Multiline Comments for Perl</p>
<p>RFC 11: Examples encoded with =also for|begin|end POD commands</p>
<p>RFC 44: Bring Documentation Closer To Whatever It Documents</p>
<p>perlpod for discussion of POD.</p>
</div>
